<html><head>
<title>HelpScan API</title>
<basefont size="4" face="Arial, Helvetica, sans-serif">
</head>
<body bgcolor="#FFFFFF" text="#000000" link="#0000CC" alink="#99AFFF" vlink="#3333FF">
<p>
<div align="center"><strong><font size="+3">HelpScan API</font></strong></div>
<div align="center"><table width="90%" cols="1" cellpadding="4" cellspacing="4" border="0" bgcolor="#FFFFFF">
<tr><td bgcolor="DEEBFF">
<strong><font size="+1">Application Meta Data</font></strong>
<p>Castle have recommended that software developers should provide some extra information (such as web address, version etc.) about their applications which can be extracted by programs such as HelpScan. However, some discussion on usenet has convinced me that the mechanism proposed by Castle could be improved upon. HelpScan, therefore, implements both the Castle system and an alternative system. Both are treated equally and you are free to do as you wish! The two mechanisms are outlined below.
<p><strong><font size="+1">Castle's Help System Variables</font></strong>
<p>Castle's suggestion is that the meta data discussed above should be included in a set of new system variables, to be set in your !Boot and !Run file. You can look at the details by visiting their <a href="http://www.iyonix.com/32bit/help.shtml">website</a>, if you wish. However, to save you the hassle, I'll reproduce (shh! don't tell anyone!) the relevant section here:
<div align="center"><table width="80%" cols="1" cellpadding="4" border="0" bgcolor="AFCFFF">
<tr><td bgcolor="FFFFFF">
<h2><font face="Verdana, Arial, Helvetica, sans-serif, homerton"
color="#0000A0">Application System Variables</font></h2> 
Applications should set the following system variables as appropriate:
<table >
<tr valign=top><td><td>&nbsp;&nbsp;<td><tt>AppName$Help</tt></td><td>&nbsp;&nbsp;<td>Full pathname to HTML help file
<tr valign=top><td><td>&nbsp;&nbsp;<td><tt>AppName$Version</tt></td><td>&nbsp;&nbsp;<td>Application's version number
<tr valign=top><td><td>&nbsp;&nbsp;<td><tt>AppName$Web</tt></td><td>&nbsp;&nbsp;<td>URL for application's home page on the World Wide Web
<tr valign=top><td><td>&nbsp;&nbsp;<td><tt>AppName$Title</tt></td><td>&nbsp;&nbsp;<td>Application's full title
<tr valign=top><td><td>&nbsp;&nbsp;<td><tt>AppName$Publisher</tt></td><td>&nbsp;&nbsp;<td>Application's publisher
<tr valign=top><td><td>&nbsp;&nbsp;<td><tt>AppName$Description</tt></td><td>&nbsp;&nbsp;<td>Concise description of the application
<tr valign=top><td><td>&nbsp;&nbsp;<td><tt>AppName$Running</tt></td><td>&nbsp;&nbsp;<td>Set to Yes when the application is running (as defined in RISC OS 3 PRM page 4-497)
</table>

These variables should be set in the !Boot and !Run files. For example:<p>

<pre>  Set AppName$Help &lt;Obey$Dir&gt;.Documents.index/html
  Set AppName$Version &quot;2.72&quot;
  Set AppName$Web &quot;http://www.octosys.co.uk/cid.html&quot;
  Set AppName$Title &quot;Caller Display&quot;
  Set AppName$Publisher &quot;Octopus Systems&quot;
  Set AppName$Description &quot;Telephone call management - displays 
      and logs incoming and outgoing telephone calls.&quot;</pre><p>

These variable may be used to provide cross-references from other documents
and also for a global help system which lists all help available on the
system. It may also be used by a search system which can search and index all
of the available help.<p>

Cross references can be achieved as shown in the following HTML fragment:<p>

<tt>
  You can upload files to the web server using the<br>
  &lt;a href=&quot;file:/&lt;FTPc$Help&quot;&gt;FTPc application&lt;/a&gt;
</tt>&nbsp;<p>

This method of linking can be used in Browse, Fresco and Oregano.<p>
</td></tr></table></div>
<p><strong><font size="+1">An Alternative System</font></strong>
<p>Instead of generating a whole load of new system variables for every application, the information can be presented in a single file, which is reference by one new system variable. For no particularly good reason I've chosen <strong><em>AppName$Meta</em></strong> to be this variable. It should point to a messages file which contains the same information as outlined above. The name of the messages file is not important to HelpScan, although it makes sense to pick some standard name, so I suggest <em>!Meta</em>. Choosing a common name has at least two uses: it allows some future program to pick out the information without using system variables at all and it can potentially be extracted by online categorisation systems, such as <a href="http://www.drobe.co.uk/">AcornSearch</a>.
<p>The <em>!Meta</em> file should be a standard RISC OS messages file containing some or all of the tokens:
<ul>
<li>Help
<li>Version
<li>Web
<li>Title
<li>Publisher
<li>Description
<li>Email
</ul>
The content of these tokens is defined exactly the same as the corresponding system variables for the Castle system. (Except <em>Email</em>, obviously, as that's an addition by me...) There is clearly the potential to expand this list further in the future. For an example of a <em>!Meta</em> file, please take a look at <a href="HelpScanAction:/Filer_Run{}<HelpScanRes$Dir>.!Meta">HelpScan's one</a>. Don't use any &quot; characters in your strings. If you do, <em>HelpScan</em> will replace them with single quotes.</p>
<p>(It's been pointed out to me that some of the information which <em>HelpScan</em> looks for may already be present in an application's main messages file. You are free to point <em>AppName$Meta</em> wherever you like, and <em>HelpScan</em> will look for the <em>_TaskName</em>, <em>_Purpose</em>, <em>_Author</em> and <em>_Version</em> tokens as replacements for <em>Title</em>, <em>Description</em>, <em>Publisher</em> and <em>Version</em> respectively, if any of the latter are missing.)
<p><strong><font size="+1">Other Information</font></strong>
<p>So, that's great. If you include the Castle variables in your programs or provide <em>AppName$Meta</em> then HelpScan will be able to examine a user's system for help information and present it in a nice HTML file. (If both are present for a specific item then the <em>!Meta</em> entry takes precedence.) There are a few things to note, however:
<dl><dt><strong>Length Limitation</strong></dt><dd>HelpScan's only a simple wee program and, as such, uses Basic string variables all over the place. System variables over 255 characters will, therefore, be truncated.</dd>
<dt><strong>Using System Variables as Links</strong></dt><dd>While the above section from Castle's website mentions the use of system variables in HTML directly, like this: <em>&lt;a&nbsp;href=&quot;file:/&lt;FTPc$Help&quot;&gt;FTPc application&lt;/a&gt;</em>, it should be noted (apart from the missing &quot;&gt;&quot;) that this appears to break relative references within those files (e.g. to images or whatever). For this reason, HelpScan writes the complete path to each file to the HTML.</dd>
<dt><strong>Only HTML?</strong></dt><dd>HelpScan will have a gander at the file which is referenced by <em>&lt;AppName$Help&gt;</em> and present the results accordingly. At the moments it says specific things for any executable files plus drawfiles, stronghelp files, text files and HTML files. If you'd like it to do anything in addition to this, get in touch.</dd>
<dt><strong>Missing Info</strong></dt><dd>HelpScan attempts to cope gracefully with a lack of information, so don't worry if you want to miss certain things out. (And <em>&lt;AppName$Running&gt;</em> is not used at all.) One thing to note is that if you miss-specify the <em>Help</em> variable, HelpScan will use the <em>&lt;AppName$Dir&gt;.!Help</em> file (if it's present) as a last-resort substitute.</dd>
</dl>
<p> That's it, I think. Happy help-system-variable-implementing!
</td></tr>
</table></div></body></html>