| RISC OS Select

                     Library
                     =======

The Library directory contains command line applications used
to provide functions for the OS and other applications. The
library is categorised into a number of directories.

When the machine starts, Run$Path (the variable that describes
where to look for commands) is set to point at every directory
in the Library.

A number of categories are defined by RISCOS Ltd to contain
applications related to specific tasks. Some of these directories
are provided with this version of Select, but it is expected that
third-parties will populate the resource with other utilities.

The categories presently defined are :

AcornC:
   Acorn C/C++ development environment tools.
   Command line tools supplied with the desktop development
   environment would live here.

Archive:
   Archival, compression and decompression tools.
   Archiving utilities such as squash, zip, tar, lha, or arj
   would live here.

GNU:
   GNU software tools.
   Tools from the GNU suite which do not easily fit into other
   categories live here. This might include such tools as grep
   and diff.

Graphics:
   Graphics processing and manipulation tools.
   Tools for converting between graphics formats would live here.

Internet:
   Internet configuration and access tools.
   Command tools for accessing files over the internet, or to set
   up connections would live here.

RISCOS:
   Reserved for RISCOS Ltd sourced or sanctioned tools.
   These are the core tools, mostly those required to boot the
   machine and general system maintenance.

Sound:
   Sound manipulation tools.
   Sound format converters, or playback tools would live here.

User:
   Local system specific tools.
   Tools which are identified by the installer will be placed
   here initially. Any tools which are specific to your system 
   should be placed here.

XML:
   XML manipulation tools.
   Tools which can be used to manipulate XML files would live
   here.

If you wish to add a new category, you should create a directory
inside <Boot$Dir>.Library and run the ScanLibs program. ScanLibs
will be run automatically on boot up and appends the names of each
of the categories to Run$Path.

New categories which are to be publicly distributed should be
registered with RISCOS Ltd such that there is no duplication of
categories, and that documentation can be provided to other
developers.


Help files
----------

Help files can be provided within each of the category directories
to provide more information about the tool. For example, for a
sound tool named 'sox', the binary would be Library.Sound.sox and
the help file would be Library.Sound.Help.sox. The information
in the Help file can be displayed using the *Help command in the
normal manner - a facility provided by the LibraryHelp module.
Information about Library tools can be obtained by using :

   *Help Library

in a similar manner to the help provided by *Help Modules.

The file format for Help files is standardised such that it can
be formatted for the above command and for specific help queries.
The file should take the form :

---
<commandname><tab><x.yy> (<dd mmm yyyy>)
<help description>
Syntax: *<command> <parameters>

Switches:
  <switch><tab><description>
---

(excluding the --- markers)

The <help description> should be unwrapped text such that it can
be formatted for the current window width. Switches and other
options should be listed in the form above to allow them to be
wrapped sensibly. <tab> characters will cause padding to the
standard 8 character offsets to be inserted but in addition will
line up lines to this point when unwrapped text reaches the
right edge of the current window.
