Help extensions

Introduction

To provide extensions to the *Help command for library commands, a service was added in RISC OS Select 2. The Help Query service allows modules to provide additional information about a requested command when the command is not present within the resident modules.

Help requests are separated into four major groups:

• Aliased commands
• Module commands
• Library commands
• General information

Before Select 2 the only help returned was that of the module commands. The new service call allows additional help messages to be returned for other keywords. This facility is used by the LibraryHelp module to display details about library commands from a text file within the library.

Library help

The LibraryHelp module searches the path Run:Help.<keyword> to locate a text file containing the help text for a command. Library commands should therefore be distributed with a Help directory containing a file of the same name which describes the command's function. For example, the command 'Finger' is described in the file 'Help.Finger'. The format of the file is important for consistency with the rest of the operating system commands.

The first line of the file must be of the form <command>, a tab, <x.yy>, a space, and then (<dd> <mmm> <yyyy>). This allows the module to interpret the line and display it when a *Help Library command is issued. For example:

IfThere<tab>1.04 (20 Dec 2001)

Subsequent lines of the file are printed in a formatted manner similar to that of SWI OS_PrettyPrint. Lines following a tab are wrapped back to the offset of the tab. The usual form of command help is:

The *<command name> command is used to <purpose>. <other usage information>.

Syntax: *<command name> <switches and parameters>

Switches:

<switch name><tab><switch description>

Authors should examine the supplied help files for other examples and aim for consistency where possible. As with all commands, the following conventions are expected:

• [] indicates optional items
• {} indicates repeated items
• <> indicates user replaced items
• other text indicates literal text

Where the syntax of a command is complex, multiple lines should be used to describe alternate forms. For example, see the help output used by INetStat. Where the syntax is still too complex to describe, either indicate that more details can be obtained by using the command with a particular syntax, refer the user to external documentation, or simplify the command.

Services