This tool is intended to make it easier for developers to create and maintain documentation and online help for their tools. It allows all the documentation to reside in one place, instead of requiring the developer to maintain html documentation in one location, and hard code 'tool tips', 'what's this?' text, etc in another location. It also allows the developer to update documentation without requiring a recompile/recompression of the script - the updated documentation files can be dropped into the DAZ Studio installation (resources), and the new online help is loaded the next time DAZ Studio is run.
The help generator is a tool that is designed to allow you to extract the 'Tool Tips' and 'What's This' text from the 'User's Manual' html documentation, so that all your documentation can be maintained in one place. This is accomplished by using html comments <!-- ... --> to outline sections and phrases in the html documentation that will be extracted to create the Tool Tips and What's This text for your plugin. The help generator recognizes commands inside of comments which outline the section of the html to be extracted. Each command must begin with the @ character, and should be the first text in the comment. The help generator supports only one command per comment, subsequent commands must each be in their own comment block to be recognized. Currently, there are only four commands:
The generated file is a .dsh file which contains XML style plain text that describes a list of help items. Each help item has a unique name, which is how it will be located by the Help Manager. Each help item will also contain Tool Tip text and/or What's This text. The .dsh file eventually needs to end up in the <DAZ_STUDIO_ROOT>/resources/ folder. When DAZStudio is started, it scans all the .dsh files in the resources folder to load the online help text.
The DAZ Studio API provides the DzHelpMgr class to allow scripts to access the extracted help at runtime. The getHelpString() and getToolTip() functions are the only two you will typically need to use to associate online help with interface components in your script. Setting the whatsThis and toolTip properties to the return values of these methods, respectively, will enable said funtionality. The name used to identify the help item within the HTML help file should be globally unique. If a help item is found with a name matching the string passed to the afore-mentioned methods, the corresponding text will be set for the widget. If a matching help item is not found, no online help will be set for the widget.
The Simple Dialog sample shows practical use of the Help Manager and the methods mentioned above. Lines of interest, in this regard, are 27, 62, 63, 74, 75, 84 and 85.
Then, in the HTML help file, we use formatted comments to specify a portion of the documentation to be used for the "What's This?" text of a given widget, as well as for an optional tooltip.
<html> <!-- @helpText SceneInfoOutput --> <!-- @{ --> <!-- @toolTip My Widget's Tip Text --> <b>myWidget:</b> This is some info about my widget. <!-- @} --> </html>
<h1>...</h2> <h2>...</h3> <h3>...</h3> <h4>...</h4> <h5>...</h5> | Headings |
<p>...</p> | A paragraph - the align attribute is supported for paragraphs. |
<center>...</center> | A centered paragraph. |
<blockquote>...</blockquote> | An indented paragraph for quotations. |
<ul>...</ul> | An unordered list. |
<ol>...</ol> | An ordered list. |
<li>...</li> | An list item. |
<dl>...</dl> | A list of definitions. |
<dt>...</dt> | A term in a list of definitions. |
<dd>...</dd> | A description in a list of definitions. |
<pre>...</pre> | For larger chunks of code. |
<div>...</div> <span>...</span> | Block grouping elements. |
<a>...</a> | An anchor or link. The name attribute is supported for anchors and the href attribute is supported for links. Links can be local, in which case they should be relative to the current document. Links may also point to an internet resource, in which case they must begin with 'http://'. Internet resources will be opened in the user's default browser. |
<em>...</em> | Emphasized - by default the same as italic. |
<strong>...</strong> | Strong - by default the same as bold. |
<i>...</i> | Italic font style. |
<b>...</b> | Bold font style. |
<u>...</u> | Underlined text. |
<s>...</s> | Strike out font style. |
<big>...</big> | A larger font size. |
<small>...</small> | A smaller font size. |
<sub>...</sub> | Subscript text. |
<sup>...</sup> | Superscript text. |
<code>...</code> | Code - same as typewriter. For large chunks of code, use pre. |
<tt>...</tt> | Typewriter font style. |
<font>...</font> | Specifies font family, size and color. Supports the following attributes: color , size , face . |
<img> | An image. Supports the following attributes: src , width , height , align . The source specifier for the image should be relative to the current document. The DAZ Studio online help browser only supports jpg and png images. |
<hr> | A horizontal line. |
<br> | A line break. |
<nobr>...</nobr> | No break - prevents word wrapping. |
<table>...</table> | A table. Supports the following attributes: bgcolor , width , border , cellspacing , cellpadding . |
<tr>...</tr> | A table row. Supports the bgcolor attribute. |
<td>...</td> | A table data cell. Supports the following attributes: bgcolor , width , colspan , rowspan , align , valign . |
Tags that are not in this list are not supported. Typically, unsupported tags and attributes will cause no errors and will simply be ignored.