About HTHELP


HTHELP is a hypertext help viewing utility. It provides HTML viewing capability from within MATLAB. In addition to viewing any HTML files, one can browse through the help text of the complete set of MATLAB Contents.m and m-files. It is a powerful complement to MATLAB's on-line help. In particular, it makes it much easier for writers of MATLAB GUI functions to incorporate on-line help from within GUI applications.

Hyper-Help parses a plain-text document for special markups (based on HTML) which allow it to format the text properly, and allow the user to roam through a series of documents. In fact, the operation of HTHELP is very similar to Mosaic and Netscape.

This file you are reading is written using HTHELP's markup language. The file is in uitools/hthelp.html, if you wish to look at the source-text.

Except for < characters, HTHELP will work on plain ascii files without any of HTHELP's formatting codes. When used in this way it provides a nice UI to display and cache long text files.

To use HTHELP from within an m-file, or anywhere, all that needs to be done is to pass it the name of the HTML file to load.

If HTHELP is called with more than one argument, it acts differently. This is how the internal commands are accessed. These are undocumented in the m-file help.

Calling HTHELP('prev', 0) reverts to the previous document. If the user has dismissed the window by pressing the "Done" button, this just makes the figure visible with the last document still loaded. If the figure is visible, then it is just as if the user has pressed the PREVIOUS button. (It stores up to the last 20 documents you have viewed as a stack.)

Calling HTHELP with no arguments loads up the main help page of MATLAB. Hyper-links are automatically built to all of the MATLAB main topics and toolboxes.

Calling HTHELP('cont', 'filename') loads up the specified file as a MATLAB Content.m file. This can be useful in displaying the contents of any MATLAB directory. Hyper-links are automatically built to the m-files described in the Contents.m file 'filename'. The Contents.m file must be written in the proper MATLAB Contents.m file format.

Calling HTHELP('func', 'mfilename') loads up the specified file as a MATLAB m-file. Hyper-links are automatically created to other related m-files. These related function names are found after the 'See also' in the m-file help text.

Try >>hthelp with no arguments at the MATLAB prompt to see how the 'cont' and the 'func' commands can be used to generate hyper-help across all of MATLAB.

Formatting HTHELP files

Formatting HTHELP Files


The first time HTHELP loads a document, it parses it for markups which are enclosed between a greater than and a less than symbol. It also parsed for escape sequences enclosed between the & and ; symbols. The markups used in HTHELP are an extended subset of HTML, the markup language used by Mosaic, Netscape and the World-Wide Web. People familiar with HTML should have no trouble with these commands. Here are the recognized markups:

<TITLE>Section Title</TITLE>
Begin and name a section. Unlike other viewers, HTHELP allows more than one section in the same file. Every time a new title is specified, HTHELP treats that section like a new document.

<A HREF="filename#optional_section_name">click here</A>
Start a hyper-link reference. This operates just as it does in HTML. The code can be any of the three types.

<A NAME="section_name">New Section</A>
Name a section. This operates just as it does in HTML. It is a marker within a file. This specifies the destination of a hyper-link.

<A RUN="MATLAB_command">bode(num, den)</A>
Run a MATLAB command. This is an extension of HTML which executes the callback from the hyper-link in the MATLAB command window. Any MATLAB command will work. The string between the markups is simply passed to the command line.

<B>Bold text</B>
Prints bold text.

<I>Italic text</I>
Prints italic text.

<TT>Typewriter text</TT>
Prints typewriter text.

<HR>
Places a horizontal rule below the present line.

<Hn>Heading</Hn>
Capital H followed by a number (1-4) sets a heading level. H1 gives the largest heading. H4 the smallest (but still larger than the default text.) /Hx (where x is any number 1-4) resets all font settings.

This is a level zero heading

This is a level one heading

This is a level two heading

This is a level three heading

Markups can appear anywhere within a line. The only restriction comes from the way markers are stored internally: they are attached as tags to the next text object created. For this reason, multiple markers without text in between do not all work.

Link-codes come in three styles. The basic form is: [filename][#marker]
Specifically, the variations are:

1. Filename codes

These codes specify a file, but not a marker, such as "hthelp.hlp". In this case, HTHELP just starts at the top of the document.
2. Full codes
These codes specify a file and a marker, such as "hthelp.hlp#Caching"
3. Relative codes
This kind of code, like "#Caching" assumes that the link is internal to the same file.
Note that marker names can contain whitespace.

Click here for an example of HTHELP source code and how it looks.

Example of Source Code Here is an example of a typical section of HTHELP code.

<TITLE>Sample Document</TITLE>
<A NAME="Sample">This is a sample piece of HTHELP code.
Click <A HREF="#Example">here</A> to view the source code again.

Click here to see how this would look. Sample Document This is a sample piece of HTHELP code.
Click here to view the source code again. Document Caching in HTHELP HTHELP automatically caches loaded documents. This means that a document's text is only parsed once. Once a document is parsed, it is in the figure so that the next time that document is requested, HTHELP merely needs to make it visible.

Documents are displayed as static text on an axis. The axis contains information about where the document came from for caching purposes. Scrolling is accomplished by simply changing the axis's y-limits. When a document is cached, all the text objects are made invisible. When a document is requested, HTHELP scans all the existing axes to see if any came from the requested file. Then it searches each of the ones which did for the exact marker. If it is found, it is made visible, otherwise the text is loaded and parsed into new axes.

The cache is limited to 20 documents by default. When the cache fills up, it automatically removes the document which has not been accessed in the longest amount of time. Keep in mind that cache maintenance has some overhead, so that very large caches will slow down normal operation. (Specifically, removing an unused document from a full cache can be slow.)