This is work in progress. Please let me finish before editing it. This message will disappear when I have.

1. Htag HOWTO

This is a howto for the program [http://www.earth.li/projectpurple/progs/htag.html htag] which should describe in some detail how to go about setting it up along with how it works.

1.1. How htag works

Before going into the depths of configuring htag, it is useful first to understand what it is doing. Hopefully this will make configuring it easier.

1.1.1. How htag is structured

htag is divided into three main parts:

  1. htag.pl
    • This is the program itself which uses the other parts

  2. HtagPlugin.pm

    • This is the library which holds many useful functions shared between plugins and htag.pl
  3. plugins
    • These are the main meat of the program. They are run to perform actions which lead to eventual creation of the sig.

If this sounds like overkill then it is. This is the sledgehammer solution to signature generation. It's not fast but I like it and it does quite a few cool things for me with just a little extra Perl.

1.1.2. htag.pl

These are the steps htag.pl goes through in order to generate a sig. Some of this may not make sense just yet. You may want to skim this and then come back to this section later.

  1. It prints a banner announcing its version.
  2. It reads the command line switches and sets up various variables. If you've not given it enough parameters it will complain at this point.
  3. It runs the configfile (see later for more information)

  4. It checks to see if changeheaders is set.

    1. If it is, then it checks to see if any of the regular expressions match any of the headers. If they do it runs the extra config file specified.

  5. If at this stage (after having run all the chosen config files) you haven't got the plugindir option defined then it dies

  6. Otherwise it will run all the plugins in the plugindir. (see the next section for how)

1.1.3. plugins

The plugins are run from plugindir once htag.pl has checked all the settings from the configfiles. Here are some points about plugins.

Plugins may return special values:

An example of this last value is probably a good idea. In the default plugin layout there are a number of plugins which each carry out their own specialised function. One picks a random tag, one picks a signature, one calculates uptime, one generates random digits and numbers and one merges all these parts together. Then we have a plugin (called asktag) which asks the user if the choice of tag is ok and if the user says no, then it returns the priority corresponding to picking a random tag and the process starts back from there. It will then reappear back at the asktag plugin and ask the user if the new tagline is suitable and so on and so forth until the user says yes, quits or heat death occurs.

1.2. Configuring htag

If what has come before has confused you then you probably don't need to worry about it too much. Just keep going and once you look at configuring htag you'll see it's not all that evil.

1.2.1. Prerequisites

You require:

The .htrc is where you should start configuring htag. You should really download the ["SampleHtagRC"] first (though you should have one in /usr/share/doc/htag/examples/sample.htrc.gz in Debian or in docs/sample-config/sample.htrc in the tarball.

1.2.2. Format of htrc

The .htrc file is actually parsed as Perl. Now if this scares you, please don't run away screaming just yet. You can get by without knowing Perl but with judicious use of cut and paste. If you do know Perl you can do cool stuff of your own invention in the .htrc without having to change htag.pl.

Basically the .htrc consists of lines which set up a hash called cfg. Most of the values are simple straightforward scalars (just normal variables if you don't know what a scalar is) some are array references (don't worry if you don't know what this means).

htag options may use ~ which will be expanded to /home/username.

1.2.3. Global configuration

There a few important global configuration options that are required by the default plugins: 

$cfg{'plugindir'}  = "~/perl/huggietag/current/plugins";
$cfg{'debug'}      = 1;
$cfg{'tmpdir'}     = "~/.htag/";
$cfg{'tmpsigfile'} = "~/.htag/sig";
$cfg{'tmptagfile'} = "~/.htag/tag";

$cfg{'nicedie'}    = 1;  # Wait until return pressed if going to die from
                         # htag.pl

The single most important option ever is plugindir. It should be set to the directory containing the plugins from the htag tarball or package. In the Debian package the plugins are in /usr/share/htag/plugins otherwise if you're installing them locally you could just leave them wherever you unpacked the tarball say ~/htag-0.0.19/plugins for the sake of argument.

debug is useful in order to get some form of trace of what htag is doing but once htag is well configured you may grow tired of seeing this output so you can set debug back to 0.

tmpdir, tmpsigfile and tmptagfile are all related. They refer to options which are used by many of the default plugins. Basically each plugin is run separately and doesn't communicate with the others except by the files it creates, modifies or deletes. tmpdir should be a directory that is private to you and which is used exclusively by htag. tmpsigfile and tmptagfile should point at distinct files. It is easiest to just leave this as it is unless you change the directory component.

nicedie does exactly what the comment says it does. It requires the user to press a key if a plugin requests death or if any fatal error occurs. This is very useful for debugging purposes.

If you are following the sample configfile you'll notice that it next talks about Multiple Config File support. I'm going to skip over this and return to it later on.

1.2.4. catsig plugin options

$cfg{'asksig'}     = 1;
$cfg{'sigdir'}     = "~/.sigs/";
# AND/OR
$cfg['sigs'}       = [ "~/.sigone", "/home/coolguy/funny/sig" ];

# sigmatch allows you to restrict the sigs in sigdir to all those in the dir
# that match sigmatch
# e.g.
# $cfg{'sigdir'}   = "~/.sigs/";
# $cfg{'sigmatch'} = '^/home/huggie/\.sigs/(bc-.*|blackcat.*)$';
# matches all the sigs in /home/huggie/.sigs/ which start with bc- or
# blackcat.

asksig tells catsig to ask if you want to use a particular signature file at run time. This way you get to choose which signature you want. Otherwise it picks one at random for you.

sigdir specifies a directory full of signatures that you wish to use.

sigs is an array reference (i.e. you need to use the funny square brackets if you don't know Perl) of signature files. This is useful if you want to specify signature files which aren't all in one directory.

Personally I prefer to put them all in one directory. But, you say, I have lots of signature files and I don't want certain people to see my bizarre ones, so how can I pick certain ones out? Ah, well you can use sigmatch. If you just want a basic htag setup then you can ignore this. sigmatch is a Perl regular expression which is applied to all the files in turn in sigdir. Only the ones that match it are allowed through and added to the signature list.

If you specify both sigdir and sigs then first all of sigs gets added to the list then any signatures in sigdir that match sigmatch. If sigmatch isn't defined then the whole of sigdir gets added.

If you are following the sample htrc then you will see sections for grep and dadadodo plugins which can safely be ignored.

1.2.5. marknlard plugin options

Inspired by the UK's BBC Radio 1 show by Mark and Lard who kept repeating "Is it foo, Mark? Sounds just like them.". You only have to define this if you want to add such quotes to your sig (as well as taglines) 

$cfg{'attributions'} = "~/perl/huggietag/current/attributions";

Defines the path to the file of attributions. The file should be in the following format: 

The Famous Five:them
Buzz Lightyear:him
Woody:him

that is name of person/band/thing and then pronoun that should be used in "Sounds just like them/him/it". Yes, this is a silly plugin. Er, what you thought taglines were serious?

1.2.6. uptime plugin options

$cfg{'uptime_time'} = 1;

This option cuts down the output from full uptime output to just "up 365 days, 23:59". Again only define it if you want to add uptimes to your sigfiles.

1.2.7. date plugin options

$cfg{'date_format'} = "%d/%m/%Y";

This option tells the date plugin what format to use. It's in the form strftime would use so see the strftime manpage.

1.2.8. simple plugin options

$cfg{'tagline_comment_char'} = '#';
$cfg{'tagfile'} = "~/taglines.tag";
#$cfg{'tagfiles'} = ["~/taglines.tag","~/others"];

# You can also use tagdir to specify a directory of taglines, and tagmatch
# to restrict the tagfiles to those that match.
# The example below includes all files in /home/huggie/.tags/ except
# /home/huggie/.tags/tech

$cfg{'tagmatch'} = '^/home/huggie/.tags/(?!tech$)';
$cfg{'tagdir'} = "~/.tags";

$cfg{'fortune'} = '/usr/games/fortune';
# Probability 0 -> 1 of using fortune instead of tagline
$cfg{'fortuneval'} = 0.3;
$cfg{'fortuneargs'} = '/home/huggie/Scratch/fortunes/matrixfortunes-0.1.0/matrix';

tagline_comment_char defines the comment character used in tagfiles. i.e. if it's set to # then lines starting with # in tagfiles will be ignored.