| Contents | Index |
MathWorks and third parties provide a rich set of toolboxes, blocksets, and target and link products. Almost all such products come with documentation that displays in the Help browser.
If you create a toolbox that works with MathWorks products—even if it only contains a few functions—you can include with it HTML help files that you and others can access using the Help browser. Providing HTML help files for your toolbox allows you to include figures, diagrams, screen captures, equations, and formatting to make your toolbox more usable.
Consider providing the following types of content in your documentation:
A start page for your toolbox (called a "roadmap")
A quick introduction to your toolbox ("getting started guide")
A detailed explanation of using your toolbox ("user guide")
Function or block reference pages
A list of examples, hyperlinked to the documentation set
Release notes, describing improvements, limitations, known bugs, and so forth
PDF versions of your HTML files (typically accessed from the roadmap page)
Except for the PDF version of documentation, each of these types of help is a set of one or more HTML pages that you create in the Editor, word processing software, or an HTML authoring environment. Many such applications can also export their source documents as PDF files.
Note You are free to organize and format your help documentation as you choose. However, if you structure your help files similarly to documentation from MathWorks, people who use it will understand where to find specific types of information. |
To learn how to create documentation for the Help browser, refer to examples. This documentation provides two folders that you can copy. These folders contain:
Template XML files containing required and optional sections, with explanatory comments
You find this folder in matlabroot/help/techdoc/matlab_env/examples/templates. Always work with copies of the files it contains when making modifications. You must edit in your own content to the templates to make them usable.
A complete toolbox with code you can run (called Upslope Area Toolbox), accompanied by extensive HTML documentation that you can view in the Help browser
Find this example in the folder matlabroot/help/techdoc/matlab_env/examples/upslope. You can use functions from the toolbox and view the help by adding the folder to the search path. However, if you choose to modify any of the files it contains, copy the entire upslope folder to a working folder.
Note Some functionality of Upslope Area Toolbox depends on Image Processing Toolbox™. If you have Image Processing Toolbox installed, clicking here brings you to its documentation. |
The following sections primarily discuss the XML template files for info.xml and helptoc.xml, showing you how to modify them to create a documentation set. The examples folder provides templates only for XML files, not HTML files. Therefore, to understand how the XML files access HTML documentation files and what those files contain, refer to corresponding files in the example Upslope Area Toolbox folder.
To add your own documentation to the Help browser, you need to:
Decide what types of documentation you want to provide and create HTML help files for your toolbox. See Types of Documentation You Can Provide.
Create an info.xml and helptoc.xml files based on examples. See Organizing Your Documentation.
Optionally create a search database to include your HTML help files in the Help browser search results. See Making Your HTML Help Files Searchable.
Add the HTML files to the Help browser, by editing and incorporating XML and other special files you create. For step-by-step instructions, see Summary of Workflow for Providing HTML Help Files.
Provide the help files to your program users, along with instructions for including the files in the Help browser.
To create HTML help files, use the MATLAB Editor, another text editor, or an HTML editing tool. If you have an XML authoring system, you can develop documentation in that environment and export it as HTML files.
If you use the Editor, enabling syntax highlighting and indenting features will help as you author HTML and XML files. The editor can automatically color syntax for .htm, .html, and .xml source files.
Tip To customize the syntax highlighting and indenting in the Editor, select File > Preferences > Editor/Debugger > Language, and choose XML/HTML. |
Verify how your HTML files appear in the Help browser. To view an HTML help file that you created, use the web function. For example, display an HTML file from the set of examples provided for this topic:
web(fullfile(matlabroot, 'help','techdoc','matlab_env' ,... 'examples','upslope','html','upslope_functions_by_cat.html'))
After you decide which types of documentation to show in the Help browser, you need to provide HTML and XML files, and link them to work together. The following sections describe how to set up your help documentation.
Note To view the content and organization of the Upslope Area toolbox documentation example, place it on the search path by clicking here, or run this command: addpath(fullfile(matlabroot, 'help','techdoc','matlab_env','examples','upslope')) |
Make a folder to hold HTML and XML files. The folder can contain subfolders to organize HTML and image files. It can also contain MATLAB program files for your toolbox, or you can locate your code files in a different folder. A typical toolbox folder contains the following kinds of elements:
Note Folders and file names that you specify are in italics in this listing. Folders are prefixed with a forward slash (/). On the right side, comments that are in italics are directives for you to follow. |
| /mytoolbox | Top level folder for toolbox documentation; can also contain your program files. |
info.xml | Indicates to MATLAB that this folder contains Help browser documentation, and points to content. Required; must have this file name. |
*.m
*.mat
*.fig
... | Program code, data, GUI, and other files for your toolbox. You can also locate program files in a separate folder or a subfolder of this one that you place on the search path. Also include a Contents.m file here summarizing the program files. |
/html | Optional subfolder for your HTML documentation content; it can have any name, which must be specified in your info.xml file. |
helptoc.xml | Defines hierarchy of help files. Required; must have this file name. |
mytoolbox_
product_page.html | Roadmap (start page) for your documentation. Use folder name followed by "_product_page.html". Optional but recommended. |
getting_started_1.html
...
getting_started_n.html | Optional content for getting started guide. |
user_guide_1.html
...
user_guide_n.html | Content for user guide. |
helpfuncbycat.html | Optional functions-by-category listing containing links to function reference HTML files. |
release_note_1.html
...
release_note_n.html | Release notes files. |
/graphics | Optional subfolder for images used in HTML pages; when you use a subfolder, HTML <image> elements must specify this path to image files. |
image_1.png
...
image_n.gif | Bitmap graphics files (usually .gif, .png, or .jpg). Do not store custom icons for the TOC here, as they cannot be found. |
/reference | Optional subfolder for function or block reference pages; when you use a subfolder, HTML <A> hyperlinks to reference pages must specify this path. |
function_1.html
...
function_n.html | Function/block reference page files. |
The Help Browser relies on several files coded in XML to recognize and present the contents of documentation and demos. These files always have the same names:
info.xml — Required file that indicates that a folder contains documentation or demos.
helptoc.xml — Required file that provides a structure for presenting the documentation set in the Contents pane.
demos.xml — Optional file to add your demos to the Other Demos section of the Contents pane. See Add Demos to the Help Browser.
In addition, you must create and provide the HTML content pages referenced by these files and graphic files for images that they display.
The info.xml file specifies the content type, name, and icon to display for your documentation set. It also identifies where to find your HTML help files, and defines items you add to the Start button. You must create a file named info.xml for each toolbox you document. When you include a file having this name in a folder and then add that folder to the search path, MATLAB adds the documentation for your toolbox to the Help browser Contents pane. The folder that info.xml identifies as <help_location> must contain your HTML documentation and a file named helptoc.xml.
The following listing is a template for info.xml that you can adapt to describe your toolbox:
Store 
<productinfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="optional">
<?xml-stylesheet type="text/xsl"href="optional"?>
<!-- info.xml file for the mytoolbox toolbox -->
<!-- Version 1.0 -->
<!-- Copyright (date) (owner).-->
<!-- Supply the following six elements in the order specified -->
<!-- (Required) element; matlabrelease content is not currently used -->
<matlabrelease>2010a</matlabrelease>
<!-- (Required) The name element appears in the Contents pane -->
<name>MyToolbox</name>
<!-- (Required) The type elementidentifies your package; pick one: -->
<!-- matlab, toolbox, simulink, blockset, links_targets -->
<type>toolbox</type>
<!-- (Optional) icon file to display in the Start button -->
<icon>sampleicon.gif</icon>
<!-- (Required if you supply help) relative path to help (HTML) folder -->
<help_location>./HTMLfolderName</help_location>
<!-- (Required if you supply help) icon used in the Help browser TOC -->
<help_contents_icon>$toolbox/matlab/icons/bookicon.gif</help_contents_icon>
<!-- - - - - - - - - - - - - Start menu - - - - - - - - - - - - - - - -->
<!-- Optional list of entries to display on Start Menu -->
<!-- Callback items are function calls or commands for toolbox -->
<!-- Refresh the Start button to see your entries -->
<!-- Remove this list if you do not want a Start button entry -->
<list>
<listitem>
<!-- The label provides the text for this menu item -->
<label>MyToolbox Documentation</label>
<!-- This callback is a command to open your documentation -->
<callback>
web ./html/mytoolbox_product_page.html -helpbrowser
</callback>
<!-- Menu item icon (a toolbox icon from the help browser ) -->
<icon>$toolbox/matlab/icons/bookicon.gif</icon>
</listitem>
<listitem>
<!-- A menu item label for a opening a GUI -->
<label>MyToolbox GUI</label>
<!-- A command to open a GUI, if any -->
<callback>mytoolboxgui</callback>
<!-- The icon for this menu item -->
<icon>$toolbox/matlab/icons/figureicon.gif</icon>
</listitem>
<listitem>
<!-- A menu item label for a opening a demo -->
<label>MyToolbox Demo</label>
<!-- A command to open a demo if any -->
<callback>mytoolboxdemo</callback>
<!-- The icon for this menu item -->
<icon>HelpIcon.DEMOS</icon>
</listitem>
<listitem>
<!-- Include call to open your Web site, if any -->
<label>MyToolbox Web Site</label>
<callback>web http://www.mathworks.com -browser</callback>
<icon>$docroot/techdoc/matlab_env/examples/webicon.gif</icon>
</listitem>
<!-- Add listitems for other features of your toolbox... -->
</list>
<!-- - - - - - - - - - - - - Start menu - - - - - - - - - - - - - - - -->
</productinfo>Note To avoid XML validation errors, include all required elements in the order specified by the template file. If you are not adding a toolbox to the Start button menu, omit the lines bracketed by <!-- - - - - - - - - - - - - Start menu - - - - - - - - - - - - - - - --> For more information, see Address Validation Errors for info.xml Files |
Replace the contents within the <matlabrelease>, <name>, <type>, and <help_location> elements with appropriate text for your toolbox. The contents of <help_location> is folder name, which usually includes a relative path. Typically, you place the help folder within the folder containing the info.xml file. You can include comments in info.xml or any other XML file. For example, you can add copyright and contact information. Lines starting with <!-- and ending with--> contain comments.
When you add a help folder to the Help browser for the first time, take the following actions:
Add your toolbox or blockset folder to the search path
Make sure that the folder you are adding is not your current folder when you perform this step.
Open MATLAB Preferences from the File menu.
Click Help, and then select the All Products button.
After MATLAB has identified your folder as a toolbox or blockset and displayed it in the Help browser, you can remove products from the Help browser you do not need to show.
To specify and structure your own documentation content, copy, edit, and save the template file, as follows:
In the Editor, open the XML template. You can either:
Copy the preceding listing and paste it into a new blank document.
Copy the info_template.xml template example file to your current folder:
copyfile(fullfile(matlabroot,'help','techdoc','matlab_env', ...
'examples','templates','info_template.xml'),pwd), ...
fileattrib('info_template.xml','+w')or click here to copy the template. Then, open the copy in the Editor.
Save the file as info.xml in your toolbox folder. Saving as a .xml file enables Editor syntax highlighting.
Replace italicized text in the listing with your own content.
If you are not adding any items to the Start menu, delete the - - Start menu - - section. If you want to customize the Start menu, you must modify the listitem elements. For instructions, see Add Your Own Toolboxes to the Start Button.
Resave the info.xml file when you finish making changes.
The info.xml file adds the HTML help files to the Help browser and items to the Start menu. The following table describes the example info.xml file provided as a toolbox template. The source file is matlabroot/help/techdoc/matlab_env/examples/templates/info_template.xml.
| XML Tag | Description | Value in Template | Notes |
|---|---|---|---|
| <matlabrelease> | Release of MATLAB | R2010a | Required. Not currently parsed, but indicates when you added help files. |
| <name> | Title of toolbox | mytoolbox | Required. The name of your toolbox that appears in the Help browser Contents pane. |
| <type> | Determines the toolbox location in the Help browser Contents | toolbox | Required. Allowable values: matlab, toolbox, simulink, blockset, links_targets, other. The Upslope Area toolbox example appears with other toolboxes. The entry has the orange book icon used for toolboxes. |
| <icon> | Icon for your toolbox help in the Start button | sampleicon.gif | If you add your toolbox to the Start button options and include a help entry there, specify an icon image file. For more information, see the <list><listitem> description. |
| <help_location> | Location of help files | ./HTMLfolderName | 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 Help browser Contents pane | $toolbox/matlab/ icons/bookicon.gif | Required if you supply HTML help files. |
| <list> <listitem> ... | Entries for Start button | various | If you also want your toolbox to appear as a Start button option, add at least one listitem. For details, see Add Your Own Toolboxes to the Start Button. |
When you set up an XML file, make sure that:
You include all required entries;
The entries are in the same order as in the preceding list and in the template;
File and folder names in the XML exactly match the names of your files and folders and use upper and lower case letters identically.
For examples, look at the info.xml file for any MathWorks product. To view one of these files:
Select Start > Desktop Tools > View Start Button Configuration Files files.
From the resulting Start Button Configuration Files dialog box, select the product.
Click Open to view the info.xml file in the Editor.
Note The info.xml files for MathWorks products contain custom constructs and features that externally supplied info.xml files cannot implement. |
You must also create a file named helptoc.xml. Place this file in the folder containing your HTML documentation files. This folder is designated as <help_location> in your info.xml file. Within a top-level <toc> element, nest <tocitem> elements to define the structure of your table of contents. This template for helptoc.xml explains its organization:
<?xml version='1.0' encoding="utf-8"?>
<toc version="2.0">
<!-- First tocitem specifies top level in Help browser Contents pane -->
<!-- This can be a roadmap page, as shown below, or a content page -->
<tocitem target="mytoolbox_product_page.html">MyToolbox Toolbox
<!-- Nest tocitems to create hierarchical entries in Contents-->
<!-- To include icons, use the following syntax for tocitems: -->
<!-- <tocitem target="foo.html" image="HelpIcon.NAME"> -->
<!-- Title-of-Section </tocitem> -->
<!-- where NAME is one of the following (use capital letters): -->
<!-- FUNCTION, USER_GUIDE, EXAMPLES, BLOCK, GETTING_STARTED, -->
<!-- DEMOS, RELEASE_NOTES -->
<!-- Icon images used for these entries are also stored in -->
<!-- matlabroot/toolbox/matlab/icons -->
<!-- A Getting Started Guide usually comes first -->
<tocitem target="mytbx_gs_top.html" image="HelpIcon.GETTING_STARTED">
Getting Started with the MyToolbox Toolbox
<tocitem target="mytbx_reqts_example.html">System Requirements
</tocitem>
<tocitem target="mytbx_features_example.html">Features
<!-- 2nd and lower TOC levels usually have anchor IDs -->
<tocitem target="mytbx_feature1_example.htm#10187">Feature 1
</tocitem>
<tocitem target="mytbx_feature2_example.htm#10193">Feature 2
</tocitem>
</tocitem>
</tocitem>
<!-- User Guide comes next -->
<tocitem target="mytbx_ug_intro.html"
image="HelpIcon.USER_GUIDE">MyToolbox User Guide
<tocitem target="mytbx_ch_1.html">Setting Up MyToolbox
</tocitem>
<tocitem target="mytbx_ch_2.html">Processing Data
</tocitem>
<tocitem target="mytbx_ch_3.html">Verifying MyToolbox outputs
<tocitem target="mytbx_ch_3a.html">Handling Test Failures
</tocitem>
</tocitem>
</tocitem>
<!-- Function reference next -->
<!-- The first file lists all of the functions, categorizing them -->
<tocitem target="function_categories.html">Functions
<!-- First category, with link to anchor in above page -->
<tocitem target="function_categories.html#1">First Category
<!-- Inside category, list its functions alphabetically -->
<tocitem target="function_1.html">function_1</tocitem>
<tocitem target="function_2.html">function_2</tocitem>
<!-- ... -->
</tocitem>
<!-- Second category, with link to anchor in above page -->
<tocitem target="helpfuncbycat.html#2">Second Category</tocitem>
<!-- Inside category, list its functions alphabetically -->
<tocitem target="function_3.html">function_3</tocitem>
<tocitem target="function_4.html">function_4</tocitem>
<!-- ... -->
</tocitem>
<!-- Third category, with link to anchor in above page -->
<tocitem target="helpfuncbycat.html#3">Third category</tocitem>
<!-- ... -->
</tocitem>
</tocitem>
<!-- Optional List of Examples, with hyperlinks to examples in other files -->
<tocitem target="mytbx_example.html"
image="HelpIcon.HelpIcon.EXAMPLES">Mytoolbox Examples
</tocitem>
<!-- Optional link or links to your or other Web sites -->
<tocitem target="http://www.mathworks.com"
image="$toolbox/matlab/icons/webicon.gif">
MyToolbox Web Site (Example only: goes to mathworks.com)
</tocitem>
</tocitem>
</toc>Be sure that file and path names exactly match those of the files and folders they identify and use upper and lower case letters identically. Your helptoc.xml can be shorter or longer than the template. The size of the file depends on the structure of your documentation and how many HTML files it contains.
Most tables of contents have two to four hierarchical levels. Lower levels can either specify subheadings within the top-level HTML file or separate HTML files. A <tocitem> can link to subheadings by specifying anchor IDs for them. For example, this one,
<tocitem target="mytbx_feature1_example.html#107">Feature 1</tocitem>
specifies a link to the named anchor #107 within the file mytbx_feature1_example.html. Anchor IDs always start with a pound sign (#).
Create anchors for referencing headings or other HTML content with <a name="#anchorid">Any content</a> elements. If your documentation set includes HTML files that are not listed in helptoc.xml, at least one file found in the table of contents must contain hyperlinks to them, so that readers can find them. For related information, see Creating Function and Block Category Listings.
To customize the helptoc template file:
In the Editor, open the helptoc XML template. You can either:
Copy the preceding listing and paste it into a new blank document.
Copy the helptoc_template.xml template example file to your current folder:
copyfile(fullfile(matlabroot,'help','techdoc','matlab_env', ...
'examples','templates','helptoc_template.xml'),pwd), ...
fileattrib('helptoc_template.xml','+w')or click here to copy the template. Then, open the copy in the Editor.
Save the file as helptoc.xml in your toolbox folder. Saving as a .xml file enables Editor syntax highlighting.
Replace italicized text in the listing with your own content.
Resave the helptoc.xml file when you finish making changes.
The info.xml file inserts your toolbox in the alphabetic listing of toolboxes or blocksets in the Contents pane. The helptoc.xml defines a hierarchy of entries within it. Each <tocitem> entry in the helptoc.xml file references one of your HTML help files or anchor IDs within that product entry. The helptoc_template.xml file that is provided as an example has the structure most toolboxes use.
You can display icons for your Contents pane entries within your toolbox. To use standard MathWorksMathWorks Help browser 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 |
 | User Guides | HelpIcon.USER_GUIDE |
 | Functions | HelpIcon.FUNCTION |
 | Blocks | HelpIcon.BLOCK |
 | Examples | HelpIcon.EXAMPLES |
 | Release Notes | HelpIcon.RELEASE_NOTES |
|
| Demos | HelpIcon.DEMOS |
To make your documentation consistent with MathWorks documentation, organize your table of contents entries in the preceding order .
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. Nest tocitem entries for the target chapters or pages within each such TOC entries, for example:
<tocitem target="get_start_top.html" image="HelpIcon.GETTING_STARTED">About Mytoolbox
<tocitem target="get_start_capabilities.html"> Capabilities </tocitem>
<tocitem> ... </tocitem>
...
</tocitem>The markup indicates that you have a file called get_start1.html that begins a getting started guide. The HTML pages it contains appear next, coded as nested tocitem elements.
Unless you prefer to hide a function from your users, provide an HTML reference page for it. If your program (.m) files contain help text, you already have the content you need to add reference pages to the Help browser. If your program files do not yet include help text, consider adding help as a first step. For details, see Add Help for Your Program Files.
You can create a reference page in an HTML authoring environment by importing the help text for a function and formatting the text. For example, you need to remove the percent sign (%) character from the beginning of each line of text, and make sure that spaces separate words. You can then format headings, words, phrases, and examples for HTML display. Finally, you can add image attributes to display graphics such as GUIs, diagrams, and graphic output from your code, and hyperlinks to See also items and other related documentation.
Consider creating reference pages from within MATLAB. You can use the capability of MATLAB to publish program scripts directly to HTML documents.
To transform help text from a program file into HTML using the publish command:
Copy the help text into a new file, and remove the code that implements the function.
Save this file as a MATLAB script (which has no initial function declaration).
Format the help text using code cell notation. For more information, see Overview of Publishing MATLAB Code.
Publish the script as an HTML file.
The following listings illustrate such a transformation for the upslopeArea.m function from the example Upslope Area toolbox files to a cell script version of its help text, upslopeArea_help.m. Find the original program files in the examples folder matlabroot/help/techdoc/matlab_env/examples/upslope. See the subfolder matlabroot/help/techdoc/matlab_env/examples/upslope/html for the cell-scripted versions and the HTML generated from publishing those files.
After formatting and saving upslopeArea_help.m, the command
publish upslopeArea_help.m
generates a file named upslopeArea_help.html in a subfolder. By default, this folder is named html, but you can specify a different name for the folder by configuring the publish command, as described in Specifying Output Preferences for Publishing. (Placing all your reference pages in the same folder simplifies accessing them.)
% upslopeArea Upslope area measurements for a DEM
%
% DESCRIPTION
% A = upslopeArea(E, T) computes the upslope area for each pixel of the
% DEM matrix, E. T is the sparse system of linear equations computed
% by flowMatrix; it represents the distribution of flow from pixel to
% pixel. A contains the upslope area for each corresponding pixel of E.
%
% Note: Connected groups of NaN pixels touching the border are treated as
% having no contribution to flow.
%
% REFERENCE
% Tarboton, "A new method for the determination of flow
% directions and upslope areas in grid digital elevation models," Water
% Resources Research, vol. 33, no. 2, pages 309-319, February 1997.
%
% ALGORITHM NOTES
% The Tarboton paper is not very specific about the handling of plateaus. For
% details of how plateaus are handled in this code, see the algorithm notes for
% the function flowMatrix. In particular, see the subfunction
% plateau_flow_weights in flowMatrix.m.
%
% EXAMPLE
% s = load('milford_ma_dem');
% E = s.Zc;
% R = demFlow(E);
% T = flowMatrix(E, R);
% A = upslopeArea(E, T);
% imshow(log(A), [])
%
% See also demFlow, dependenceMap, fillSinks, flowMatrix, postprocessPlateaus.
% Steven L. Eddins
% Copyright 2007-2009 The MathWorks, Inc.
function A = upslopeArea(E, T)
requiresIPT(mfilename);
% Right-side vector is normally all ones, reflecting an equal contribution
% to water flow originating in each pixel.
rhs = ones(numel(E), 1);
% Connected groups of NaN pixels that touch the border do not contribute
% to water volume.
mask = borderNans(E);
rhs(mask(:)) = 0;
A = T \ rhs;
A = reshape(A, size(E));
%% upslopeArea
% Upslope area measurements for a DEM
%
%% Description
% |A = upslopeArea(E, T)| computes the upslope area for each pixel of the
% DEM matrix, |E|. |T| is the sparse system of linear equations computed
% by |flowMatrix|; it represents the distribution of flow from pixel to
% pixel. |A| contains the upslope area for each corresponding pixel of |E|.
%
% Note: Connected groups of NaN pixels touching the border are treated as
% having no contribution to flow.
%
%% Reference
% Tarboton, "A new method for the determination of flow
% directions and upslope areas in grid digital elevation models," _Water
% Resources Research_, vol. 33, no. 2, pages 309-319, February 1997.
%
%% Algorithm notes
% The Tarboton paper is not very specific about the
% handling of plateaus. For details of how plateaus are handled in this
% code, see the algorithm notes for the function |flowMatrix|. In
% particular, see the subfunction |plateau_flow_weights| in |flowMatrix.m|.
%
%% Example
s = load('milford_ma_dem');
E = s.Zc;
R = demFlow(E);
T = flowMatrix(E, R);
A = upslopeArea(E, T);
imshow(log(A), [])
%% See also
% <demFlow_help.html |demFlow|>, <dependenceMap_help.html |dependenceMap|>,
% <fillSinks_help.html |fillSinks|>, <flowMatrix_help.html |flowMatrix|>,
% <postprocessPlateaus_help.html |postprocessPlateaus|>.
%%
% Copyright 2007-2009 The MathWorks, Inc.
As you see, the script file, upslopeArea_help.m, does not contain the lines of code that implement the function or comments embedded in that code. However, the file does contain code for the example of using the function and all the help text. The See also entries to other toolbox functions are hyperlinks, which you manually edit to use the syntax <function_name_help.html function_name>.
When you show the published output file with web(upslopeArea_help.html), the beginning of the reference page resembles the following figure.
Near the end of the published reference page, a screen capture from imshow appears, automatically inserted by publish.
To make your reference pages more useful, also include a Functions (or Blocks, for blocksets) entry for them in the Contents pane of the Help browser. Expanding one of these entries can display a list of categories. Each category lists the associated functions (or blocks), along with a brief description of the category and descriptions of each function (or block).
If you supply reference help files, you can provide a classified listing of them. HTML help summaries are similar to Contents.m files, but display in the Help browser. If you already have a Contents.m file that lists all your public functions, you can use it as the basis for creating a categorical listing in HTML. If you do not have a Contents.m file, consider creating one to round out your toolbox. For more information, see Help Summary for Your Program Files (Contents.m).
To include a Function-by-Category listing, create an HTML page for it. Use the following example to learn how to edit and mark up your Contents.m file, and then publish it to HTML. You can name the output file helpfuncbycat.html, as shown, or whatever you prefer. Within Contents.m, organize your functions or blocks into categories that you define. Each category begins a new cell. When you publish the file, each category displays as a heading and has an anchor ID (from #1 to #n).
The helptoc_template.xml file use category names and anchor IDs in <tocitem> elements in its reference section. In the template file, the section for function reference includes links to the categorical listing page, category anchors within it, and individual reference pages.
The following example shows the section of the helptoc.xml template file that organizes function reference pages. Publishing helpfuncbycat.m created anchor IDs #1, #2, #3, ... in output file helpfuncbycat.html to which some <tocitem> elements refer:
<toc version="2.0">
<!-- ... -->
<!-- Function reference next -->
<!-- The first file lists all of the functions, categorizing them -->
<tocitem target="function_categories.html">Functions
<!-- First category, with link to anchor in above page -->
<tocitem target="function_categories.html#1">First Category
<!-- Inside category, list its functions alphabetically -->
<tocitem target="function_1.html">function_1</tocitem>
<tocitem target="function_2.html">function_2</tocitem>
<!-- ... -->
</tocitem>
<!-- Second category, with link to anchor in above page -->
<tocitem target="helpfuncbycat.html#2">Second Category</tocitem>
<!-- Inside category, list its functions alphabetically -->
<tocitem target="function_3.html">function_3</tocitem>
<tocitem target="function_4.html">function_4</tocitem>
<!-- ... -->
</tocitem>
<!-- Third category, with link to anchor in above page -->
<tocitem target="helpfuncbycat.html#3">Third category</tocitem>
<!-- ... -->
</tocitem>
</tocitem>
</toc>Tip Copy the preceding XML code and paste it into an editor. Delete any <tocitem> ... </tocitem> lines that you do not need, and replace text italicized in the listing with your own content. Then, paste your code intohelptoc.xml, replacing the template content section for reference pages displayed here. |
Italics in the listing indicate strings you need to replace with your own category, file, function, and anchor names and other text. If you place help files for functions or blocks in a subfolder of the one containing your helptoc.xml file, include a relative path in the target attribute for each <tocitem>. For example, if you place function reference pages in a subfolder called /reference, you would specify the target as follows:
<tocitem target="./reference/function_1.html">function_1</tocitem>
As mentioned previously, a functions-by-category listing works like a Contents.m file. The following example shows how the Contents.m file for the Upslope Area toolbox example was marked up and published to create an HTML page that categorizes the toolbox functions and links each function to its reference documentation.
Note If you perform the following procedure, first copy the Upslope Area toolbox Contents.m file to a working folder so you do not overwrite the file or the files upslope_functions_by_cat.m and upslope_functions_by_cat.html that following the example generates. |
Edit the original Upslope Area toolbox Contents.m file:
% Upslope Area Toolbox % Version 2.0 09-Dec-2009 % % Requires Image Processing Toolbox(TM). % % Flow Direction. % demFlow - Downslope flow direction for a DEM % facetFlow - Facet flow direction % flowMatrix - Linear equations representing water flow % pixelFlow - Downslope flow direction for DEM pixels % % Preprocessing and Postprocessing. % borderNans - Find NaNs connected to DEM border % fillSinks - Fill interior sinks in a DEM % postprocessPlateaus - Replace upslope areas for plateaus with mean value % % Hydrological Applications. % dependenceMap - Dependence map for water flow in a DEM % influenceMap - Influence map for water flow in a DEM % upslopeArea - Upslope area measurements for a DEM % % Display. % visDemFlow - Visualize flow directions in a DEM % visMap - Visualize influence or dependence map for a DEM % % Data. % milford_ma_dem.mat - Sample DEM data provided by USGS and distributed % via Geo Community (geoworld.com), a USGS data % distribution partner. The data set is a 1:24,000-scale % raster profile digital elevation model. Download the % "Milford" file from the "Digital Elevation Models (DEM) % - 24K Middlesex County, Massachusetts, United States" % page: % % http://data.geocomm.com/catalog/US/61059/526/group4-3.html % % natick_ned* - Sample 1/3 arc-second DEM data for a region in Natick, % Massachusetts. Downloaded from the The National Map % Seamless Server (http://seamless.usgs.gov/index.php). % % % Steven L. Eddins % Copyright 2007-2009 The MathWorks, Inc.
In the Editor, mark up Contents.m as follows:
Add a top-level heading, Functions by Category.
Format the five categories (Flow Direction, Preprocessing and Postprocessing, Hydrological Applications, Display, and Data) with double percent signs (%%). Doing so turns the sections into code cells, which become section headings in HTML.
Place an asterisk (* ) in front of each function name to mark it as a bullet in HTML.
Format each function name as a hyperlink to its own reference page. In the Upslope example, function reference pages were created by extracting the function help text to files called functionName_help.m, which were then published as functionName_help.html.
.
The complete markup of Contents.m into a functions-by-category source listing looks like the following example:
%% Functions by Category % Upslope Area Toolbox % Version 2.0 09-Dec-2009 % % Requires Image Processing Toolbox(TM). % %% Flow Direction % * <demFlow_help.html |demFlow|> - Downslope flow direction for a DEM % * <facetFlow_help.html |facetFlow|> - Facet flow direction % * <flowMatrix_help.html |flowMatrix|> - Linear equations representing water flow % * <pixelFlow_help.html |pixelFlow|> - Downslope flow direction for DEM pixels % %% Preprocessing and Postprocessing % * <borderNans_help.html |borderNans|> - Find NaNs connected to DEM border % * <fillSinks_help.html |fillSinks|> - Fill interior sinks in a DEM % * <postprocessPlateaus_help.html |postprocessPlateaus|> - Replace upslope areas % for plateaus with mean value % %% Hydrological Applications % * <dependenceMap_help.html |dependenceMap|> - Dependence map for water flow in a DEM % * <influenceMap_help.html |influenceMap|> - Influence map for water flow in a DEM % * <upslopeArea_help.html |upslopeArea|> - Upslope area measurements for a DEM % %% Display % * <visDemFlow_help.html |visDemFlow|> - Visualize flow directions in a DEM % * <visMap_help.html |visMap|> - Visualize influence or dependence map for a DEM % %% Data % * milford_ma_dem.mat - Sample DEM data provided by USGS and distributed % via Geo Community (geoworld.com), a USGS data % distribution partner. The data set is a 1:24,000-scale % raster profile digital elevation model. Download the % "Milford" file from the "Digital Elevation Models (DEM) % - 24K Middlesex County, Massachusetts, United States" % page at http://data.geocomm.com/catalog/US/61059/526/group4-3.html. % * natick_ned* - Sample 1/3 arc-second DEM data for a region in Natick, % Massachusetts. Downloaded from the The National Map Seamless Server % (http://seamless.usgs.gov/index.php). % %% Source % Steven L. Eddins % Copyright 2007-2009 The MathWorks, Inc.
Save your formatted file as upslope_functions_by_cat.m in your current folder (in this case, called helptests).
Publish the file, and view the resulting HTML file:
publish upslope_functions_by_cat.m ans = C:\myfiles\upslope\helptests\upslope_functions_by_cat.html web(ans)
If you want the Help browser to include your documentation in its search results, provide a search database for your HTML help files. MATLAB can create a database for you with one command.
The example uses the info.xml file for the Upslope Area toolbox with the help_location specified as C:\myfiles\upslope\html.
To create the database files:
If you have not already done so, add the folder containing your info.xml file to the search path.
For the example, add the C:\myfiles\upslope folder to the path.
Create a searchable database by running
builddocsearchdb('full_path to_help_location')For the example, assuming your help files are in C:\myfiles\upslope\html, run:
builddocsearchdb ('C:\myfiles\upslope\html')You must use the functional form when you call builddocsearchdb (with the folder location in single quotes inside parentheses).
builddocsearchdb creates a folder named helpsearch in the help_location folder. For the example, this command creates the folder C:\myfiles\upslope\html\helpsearch.
Each time you run it, builddocsearchdb generates three files in helpsearch:
A file called deletable.
A file called segments.
A file having a cfs extension with a name that varies.
To verify that your help files can be searched, 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.
The next figure shows a search of the Upslope Area toolbox and other documentation for the terms facet flow.
To include your HTML help files in the Help browser Contents pane, you must create and supply two XML files that the Help browser requires, plus HTML, and image files you develop for your documentation. You must also tell recipients of your software how to install these files. The following steps summarize the steps to take to add your documentation to the Help browser and distribute it to others.
This procedure uses template XML files that you need to customize. To see examples of content and how the files are organized, refer to a complete example of user documentation, the Upslope Area toolbox. To view the Upslope documentation in the Help browser, click here, or run
addpath(fullfile(matlabroot, 'help','techdoc','matlab_env','examples','upslope'))
The Upslope Area Toolbox now appears in the Contents pane (toolboxes are alphabetized), as the following graphic displays. The appearance of your contents pane depends on what products you have installed.
Tip Print or bookmark this page of instructions. Then, when you place your own HTML pages in the Help browser, you can view the instructions at the same time. |
Create or choose a folder for storing your help files. You must have write access to the folder. You can use the same folder that contains your toolbox code.
For the Upslope Area toolbox example, name the folder upslope.
Add an info.xml file to the folder. This file identifies the folder as one that contains documentation. To add this file, either click here or follow these two steps:
Copy
copyfile(fullfile(matlabroot,'help','techdoc','matlab_env', 'examples','templates','info_template.xml'),pwd)
to the folder.
For example, copy the file to upslope.
Verify that the copied info_template.xml file is writable. If it is read-only, make it writable with:
fileattrib('info_template.xml','+w')Rename the copy of info_template.xml to info.xml. The file must have this name.
Within your current folder, create a new folder to contain files for the Help browser Contents. (The info.xml points to this folder as <help_location>.)
For the example, in mytoolbox, create a folder named html.
Make the new folder your current folder.
For the example, cd html.
Add a helptoc.xml file to the empty folder. This file organizes the Help browser table of contents for your toolbox. To add this file, either click here or follow these two steps:
Copy the helptoc_template.xml file to your working directory:
copyfile(fullfile(matlabroot,'help','techdoc','matlab_env', 'examples','templates','helptoc_template.xml'),pwd)
to the folder.
For example, copy the file to mytoolbox/html.
Verify that the copied helptoc_template.xml file is writable. If it is read-only, make it writable with:
fileattrib('helptoc_template.xml','+w')Rename the copy of helptoc_template.xml to helptoc.xml. It must have this name.
Move the HTML help files you created, as described in Summary of Creating and Installing HTML Help Files, to the folder containing your helptoc.xml file. Also move to the folder any files that the HTML files reference, such as image files.
The XML files in the examples/templates folder have no accompanying HTML files. You can, however, view files for the example Upslope Area toolbox and learn how its helptoc.xml file organizes HTML documentation content. For details, see Organizing Your Documentation
In the Editor, open, modify, and save your info.xml, helptoc.xml files.
For details about changes to make, see:
Verify that the Help browser Filter by Product preference is set so that your toolbox appears in the display. To set the Filter by Product preference:
Access the Help Preferences pane by selecting File > Preferences > Help.
Under Filter by Product, select All products.
Add the folder to the search path.
For example, add upslope to the search path.
View your HTML help files in the Help browser Contents pane.
Review the browser display, and verify that there are no errors. MATLAB automatically validates info.xml files and reports any problems to the Command Window. For information about addressing the problems, see Address Validation Errors for info.xml Files.
If you provide your documentation to others, make sure that you include all files and folders:
HTML files.
Images or other files referenced by the HTML files.
Your info.xml and helptoc.xml files.
Your search database files, if any.
You can use zip or gzip to create an archive of the folders.
Instruct recipients of your documentation how to display it. They need to:
Unzip the archive containing the help files to any disk location they prefer to use, and add the help folder to the search path.
Verify that your toolbox is selected in the Filter by Product Help preferences. Selecting it enables your toolbox to appear in the Contents pane of the Help browser.
If your toolbox still does not appear in the Contents pane, suggest removing its folder from the search path and then adding back to the path. The toolbox folder cannot be the current folder during this operation.
Inform your users which documentation features you support. For example:
If you provided search database files, mention that Help browser search results will include your documentation.
Alternatively, you can instruct the users to generate a search database with the builddocsearchdb function after they set up your files.
 | Add Help for Your Program Files | Add Demos to the Help Browser |  |
Includes the most popular MATLAB recorded presentations with Q&A; sessions led by MATLAB experts.
| © 1984-2011- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |
