STT(1)

NAME
stt - standard text tool

SYNOPSIS
stt [modifiers] form [formargs...] stt [modifiers] (--edit|--new) form [formargs...] stt [modifiers] --grep pattern [formargs...] stt (--list|--syntax[form]) stt --sign form

DESCRIPTION
stt is a tool to use and maintain form letters (standard texts). It interfaces with the mail systrem (currently only MH and MBOX). The standard action is to produce a reply to the current message using the form specified. For a description of the format of the forms see stt(5). modifiers are flags, that change stt behaviour during different operations. A deprecated sequence +folder msg can be specified to tell the mail system which message to reply to. It works only for MH system and have to be exactly two arguments of the form specifying the folder and the message. Specifying only one of these does not work. It's recommended to use more general --folder [folder name][:message] form to specify alternative mailbox and message. form specifies the form by the name of the file. It'll be looked for in the directories, specified in STTPATH environment variable. formargs are the arguments configured in the form, see stt(5). stt performs the following operations:

-e form
--edit form
    Calls the editor with the form mentioned. This is the only legal way to edit the form (see "Security notes"). The appropriate revision control mechanisms will be used automatically if the form appears to be under revision control.

-n
--new form
    Is used to create a new form in the first directory of STTPATH. stt will call the editor, supplying the builtin template as a start document. This command will fail, if such document already exists in this directory. The appropriate revision control mechanisms will be used automatically if the directory appears to be under revision control.

--sign form
    Calculates and prints MD5 hash of the form (see "Security notes").

-g pattern
--grep pattern
    select a form by it's contents. This will search (grep) through all the forms and use the one which contains the pattern specified in pattern if only one such form exists. If more than one matching form is found, it will display a short description of all matching forms. This is for the NCC manager who cannot remember the names of the forms but sometimes remembers the text in the templates. You can use perl5(1) regular expressions in pattern... with caution.

-l
--list
    list the short descriptions of all forms, one line per form.

--syntax [form]
    Check syntax of all STTs or just a "form"

The following modifiers are recognized by stt:

-c
--create
    creates a new message instead of responding to the current MH message.

-r
--respond
    responds to the current MH message instead of creating a new message. This is the default. The flag is intendet to override a different default set in the form.

-p
--prompt
    force prompting. All variables will be prompted for, including the already defined variables.

--strict
    This force stt to stop on a syntax errors (as it should be, but disabled for version 1.00 STTs).

--dump
    This allows to dump generated by stt perl5 code to STDERR, what allows to see, what internaly goes on in STT.

--sttpath path
    Allows to override default path(s) to STT files, taking precidence on environment variable.

--folder [folder name][:message]
    This is extended syntax to replace the +folder message format in stt v1. Meaning of the "folder name" depends from the current mailbox driver, and can be a path to file in unix mbox format(MBOX) or name of MH folder(MH). This is an optional parameter. Message is the message within the "folder" and can be numeric (for MBOX and MH) or just a hook name, like "cur" for MH.

--mailbox FORMAT
    This allows to override what default mailbox driver should be used, currently available are MH and MBOX. This is how to read mail with stt.

--mailer MAILER
    This allows to override mailer system, that uses to send outgoing message.
    Currently only MH is working, MBOX just outputs message    to STDOUT.

Configuration
stt has it own configuration file(s). System-wide configuration resides in /etc/stt.conf and per-user config is in $HOME/.sttrc. Allowed options are: PROTECT - colon separated list of directories, protected from unauthorized editing.
AUTHGROUPS - comma separated list of the user groups, members of which are allowed to edit code in protected stt-templates.
STTPATH - search path for forms, also ':' separated.
TMPDIR - directory, where to place temporary files.
MAILDIR - directory, where users's system mailbox resides. Can be used by MBOX driver to access messages.
WARNINGS - can disable warnings ($^W=0), produced by the included modules. Still, it's not recomended to do that. Possible values are - 'NO', 'OFF', '0' to turn them off and 'YES', 'ON', '1' to turn on. Case of the switches is not relevant.

Comments starts at the begining of the line with the '#' sign. Empty strings are ignored.

Security notes

To protect STT-template from accident or unauthorized changes 3 stages of protection were introduced. First of all, stt tries to protect code part of the form from modifying by unprivileged users (like hostmasters:). The only legal way to edit form is to use "stt --edit form" call. stt amoung other things in this case automaticaly adds MD5 checksum and will check it during the normal run. If checksums aren't equal it'll refuse to run...

Users, that belong to "privileged" groups, like wheel and softies can modify whole form all across the filesystem.

For common users there is a list of protected directories, where they can edit only text part of the form. That directories are listed in PROTECT section in stt configuration file (see "Configuration"). In all other directories they have ability to modify the whole form template.

            +-----------+-----------------------+
            | | directory in PROTECT |
            | +-----------+-----------+
            | | yes | no |
            +-----------+-----------+-----------+
            | member of | | |
            |privileged | text+code | text+code |
            | group | | |
            +-----------+-----------+-----------+
            | | | |
            |common user| text only | text+code |
            | | | |
            +-----------+-----------+-----------+

Stt versions
A version numbers was introdused for form templates. Now, default version is 1.00, which corresponds to original stt. New (this one) stt has version 2.00, with changed syntax.

FILES
/etc/stt.conf - System-wide stt configuration file.
$HOME/.sttrc - User-specific stt configuration file.
/ncc/stt - standard location of forms if no STTPATH
/local/stt - standard location of forms if no STTPATH

ENVIRONMENT
EDITOR - to determine just that
STTPATH - search PATH for the forms
SIGNAME - builtin variable for signature
USER - login name of the user

SEE ALSO
stt(5), mh(1), comp(1), anno(1), perl5(1)

AUTHORS
Daniel Karrenberg <dfk@ripe.net>
Timur Bakeyev <timur@ripe.net>
Tony Bates <tony@ripe.net> contributed the RCS interface, all 9 lines of it. :-)

BUGS
Supports only MH as a mail system. supporting RCS as version control mechanism. The mail system interfaces are isolated in the code. Roll your own and feed it back to us please.