ucs-tool - Execute UCS/Perl scripts from contrib/ tree
ucs-tool --list [--category | --category=<cat>] ucs-tool --doc <tool> [<ucsdoc options>] ucs-tool [--category=<cat>] <tool> ...
In addition to the UCS/Perl programs, which perform general tasks and will be of interest to most users, the UCS distribution includes a number of UCS/Perl scripts for more specific applications. These scripts are not directly accessible as command-line programs. They are organised into a hierarchical set of categories in the contrib/ directory tree, and can be invoked through the ucs-tool program. If you want to add your own scripts to this tree, read the section on WRITING CONTRIBUTED SCRIPTS below.
When the --list (or -l) option is specified, ucs-tool lists all available UCS/Perl scripts from the contrib/ tree, grouped by category. Add the option --category (or --cat or -c) for a listing of category names and descriptions (without the individual tools). You can also use the special short form ucs-tool -lc for this purpose. When an argument is given for --category, only scripts from the specified category are listed (the category name is case-insensitive).
Some scripts may provide manual pages in the form of embedded POD documentation. Such manual pages can be displayed with the --doc (or -d) flag, followed by the name of the script. See the section on SCRIPT INVOCATION below for details on how script names are matched. ucs-tool uses the ucsdoc program to format manual pages and accepts ucsdoc options (such as -ps and -tk) after the tool name.
In order to invoke one of the contributed UCS/Perl scripts, simply specify its name (as shown by the --list option), followed by command-line arguments for the selected script, e.g.
ucs-tool dispersion-test -m 3 -N 100000 -k 100 -V 2500
All contributed scripts should include a short help page that can be displayed with the --help (or -h) option. Note that this is a script option and therefore must be specified after the script name:
ucs-tool dispersion-test --help
Recall that full manual pages, when available, can be displayed with the --doc option specified before the script name (as described above).
Script names are case-insensitive, and it is sufficient to specify a unique prefix of the name. For instance, you can invoke the print-documentation script with the short name ucs-tool print or ucs-tool print-doc. It may be easier to find a unique prefix when the search space is reduced to a specific category with the --category (or -c) option.
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).
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.
Copyright 2004-2005 Stefan Evert.
This software is provided AS IS and the author makes no warranty as to its use and performance. You may use the software, redistribute and modify it under the same terms as Perl itself.