

	USER-CONTRIBUTED UCS/PERL SCRIPTS


Contributed UCS/Perl scripts are collected in a directory tree rooted in
System/Perl/contrib/. Each subdirectory corresponds to a script
category. These categories are organised hierarchically according to the
directory structure (for instance, "--list --category=Import" lists all
scripts found in the directory Import/ and its subdirectories, such as
Import/NSP/ and Import/CWB/). The file CATEGORIES contains a listing of all
known categories with short descriptions (category names and descriptions must
be separated by a single TAB character).

Contributed scripts can conveniently be invoked with the ucs-tool program
(see "ucsdoc ucs-tool" for more information).  This program locates scripts
in the entire contrib/ tree, matches partial names, and displays categorized
listings of the available scripts. 

If you want to add your own UCS/Perl scripts to the repository, you should put
them in the Local/ directory (which is reserved for scripts that are not part
of the UCS distribution). This is often the easiest way to make a UCS/Perl
script available to all users of a UCS installation. Note that script files
*must* have the extension ".perl" or ".pl", which is not part of the script
name (e.g., the script nsp2ucs in the category Import/NSP corresponds to the
disk file Import/NSP/nsp2ucs.perl in the contrib/ tree). You can also put your
script in a different category or define your own categories (which you must
add to the CATEGORIES file), but this will interfere with upgrading to a new
UCS release. You are encouraged to share scripts with other users. To do so,
please send them to the author (or maintainer) of the UCS system, indicating
which category they should be included in.

Unlike ordinary UCS/Perl scripts, scripts placed in the contrib/ tree do not
have to be configured with ucs-config. They also do not have to be executable
and start with a shebang ("#!") line. When invoked with the ucs-tool program,
the necessary settings are made automatically.  Contributed scripts that
require "private" modules (which are not installed in a public directory) can
place them in a subdirectory named lib/ (relative to the location of the
script file), or in further subdirectories as required by the module's
name. The lib/ directory tree is automatically added to Perl's search
path. Necessary data files should be wrapped in Perl modules and stored in the
lib/ subtree as well. For instance, assume that a script named my-script in
the Local category (corresponding to the script file Local/my-script.perl)
uses the private module My::Functions. This module can automatically be loaded
(with "use My::Functions;") from the file Local/lib/My/Functions.pm in the
contrib/ directory tree.

All contributed UCS/Perl scripts should include a short help page describing
the script's function and command-line arguments, which is displayed when the
script is invoked with "--help" or "-h". Script authors are also encouraged to
write full manual pages as embedded POD documentation (which can then be
displayed with "ucs-tool --doc"), but these are not mandatory.

The UCS distribution includes a number of UCS/Perl scripts in the contrib/
tree. These scripts are more specific than the UCS/Perl programs, which
perform general tasks that will be of interest to most users.

