SYNOPSIS
DESCRIPTION
OPTIONS
PREFERENCE FILES
QUOTE FILES
TEMPLATE FILES
BUGS
AUTHORS

SGROTUM

NAME

sgrotum - an email signature rotumbulator

SYNOPSIS

sgrotum [options] <preference-file>

DESCRIPTION

Sgrotum (SiGnature ROTUMbulator) is a simple to use but very flexible tool for managing email and newsgroup signatures. It works by keeping a list of signature templates from which it picks at random (or by rotation), optionally inserting randomly selected quotations where and how you specify.

OPTIONS

-f, --fast

Maybe useful if your quote file is enormous. The drawback is that some otherwise suitable quotations will not be picked.

-h, --help

Display usage information and exit.

-n, --no-write

Don't write target signature file. If no target is specified in preferences, this has no effect.

-s, --show

Write result to stdout. This is the default action if no target file is specified in preferences.

-v, --version

Display the program's version number and exit.

PREFERENCE FILES

Here's an example (say, ~/.sgrotum/my.pref):

         [target]
         ~/.signature

         [dash]
         yes

         [mode]
         rotate

         [quotes]
         ~/.sgrotum/quotes.txt

         [templates]
         ~/.sgrotum/sig1
         ~/.sgrotum/sig2
         ~/.sgrotum/sig3
         ~/.sgrotum/sig4

         [current]
         1

The target section specifies the signature file you want written. This section is not required. If no target is given, the signature will be written to stdout.

The dash section contains either "yes" or "no". If it's yes, the program will write "-- " (dash dash space) as the first line of your signature. This section is not required. The default is "yes".

The mode section contains either "rotate" or "random" and specifies how templates should be selected from the templates section. The mode section is not required. The default is "random".

The quotes section specifies the default quote file. Not required if you won't be using quotations, or if your templates all specify quote files of their own.

The templates section lists one or more signature template files. This section is required.

The current section is automatically written by sgrotum if mode is "rotate" and the templates section lists more than one file. This is always the final section. Anything added below it will be lost.

QUOTE FILES

Quote files contain... quotations, usually. Each quote must be on a line of its own. Blank lines and lines whose first non-space character is a hash (#) will be ignored.

If using the --fast option, you'll get better results if your quotes do not begin or end with space characters and do not contain consecutive space characters.

TEMPLATE FILES

A template can be an ordinary signature file. Alternatively, it can contain instructions telling the program how and where to insert quotations.

The simplest template with quote insertion is a file containing this single line:

       [quote]

On meeting this, sgrotum will add a quote using default settings: the quote will come from the quote file specified in preferences, and the resulting signature will measure no more than 70 characters across and be no more than 4 lines long.

For something more interesting, attributes can be added to the [quote] line. For example:

       [quote x1=10 x2=60 y1=1 y2=3 align=center]

Multiple quote lines are allowed, resulting in multiple quotes:

       [quote x1=2  x2=21 y1=2 y2=3]
       [quote x1=25 x2=44 y1=2 y2=3]
       +--------------------+ +--------------------+
       |                    | |                    |
       |                    | |                    |
       +--------------------+ +--------------------+

Note that, as far as y1 and y2 are concerned, line 1 is the first line that's not a [quote] line. Any characters from line 1 down - so long as they're not overwritten by an inserted quote - will be included in the final signature.

The allowed attributes are:

x1=NUM x2=NUM y1=NUM y2=NUM

Box coordinates. Defaults are 1, 70, 1 and 4 respectively.

align=left|right|center

Quote alignment within box. The default is left.

minlen=NUM

The minimum length, in characters, of the quote you'd like selected. Useful if you want to avoid a mostly empty box. The default value is 0.

strip=yes|no

This affects word splitting and space removal. The default is "yes". Use strip=no only if you're trying to use lines of ASCII art as quotes. YMMV.

file="filename"

Specifies a quote file, overriding the default. The default is the quote file specified in preferences.

env=VARNAME

If the named environment variable exists, its value will be used in place of a quote.

BUGS

I expect so.
Please report them to <trmusson@ihug.co.nz>

AUTHORS

Timothy Musson